/**
 * @Date: Mar 4, 2010 6:46:36 PM
 */
package com.philip.journal.core.controller;

import java.io.IOException;
import java.util.List;
import java.util.Map;

import javax.servlet.http.HttpServletResponse;

import com.philip.journal.home.service.util.BeanToMapConverter;

/**
 * @author cry30
 */
public interface ResponseHandler {

    /** Success attribute name. */
    String SUCCESS = "success";

    /** Error message attribute name. */
    String ERRORMSG = "errormsg";

    /** List of Error attribute name. */
    String ERRORS = "errors";

    /** Error short description attribute name. */
    String DESC_SHORT = "errorDescShort";

    /** Error long description attribute name. */
    String DESC_LONG = "errorDescLong";

    /**
     * Required bean to map converter instance..
     *
     * @return Customizable bean map attribute converter.
     */
    Map<String, BeanToMapConverter> getConverterFactoryMap();

    /**
     *
     * @param <T> Bean type.
     * @param response Standard servlet response.
     * @param list List of beans.
     * @param converter Bean to map converter/customizer.
     * @throws IOException Required for serialization of the object into the view.
     */
    <T> void respondList(HttpServletResponse response, List<T> list, BeanToMapConverter converter)
            throws IOException;

    /**
     * Places the list on a place holder attribute. The resulting object is contains the actual list referred
     * the specified property.
     * 
     * @param <T> Bean type.
     * @param response Standard servlet response.
     * @param list List of Beans.
     * @param placeHolder property holder defined by the view.
     * @throws IOException Required for serialization of the object into the view.
     */
    <T> void respondListHolder(HttpServletResponse response, List<T> list, String placeHolder)
            throws IOException;

    /**
     * @param response Standard servlet response.
     * @param param Map of success property values.
     * @param placeHolder property holder defined by the view.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondSuccess(HttpServletResponse response, Map<String, Object> param, String placeHolder)
            throws IOException;

    /**
     * Respond to a successful request.
     *
     * @param response Standard servlet response.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondSuccess(HttpServletResponse response) throws IOException;

    /**
     * @param response Standard servlet response.
     * @param param Map of success property values.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondSuccess(HttpServletResponse response, Map<String, Object> param) throws IOException;

    /**
     * Responds an error message with a short description with a long description ideal for a friendly user
     * message with expandable detail section for the complete error message.
     *
     * @param response standard servlet response instance.
     * @param errorShort - short error message.
     * @param errorLong - complete error message.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondFail(HttpServletResponse response, String errorShort, String errorLong) throws IOException;

    /**
     * @param response standard servlet response instance.
     * @param errorMessage fail error message.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondFail(HttpServletResponse response, String errorMessage) throws IOException;

    /**
     *
     * @param response standard servlet response instance.
     * @param errors Map of error messages.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondFail(HttpServletResponse response, Map<String, String> errors) throws IOException;

    /**
     *
     * @param response standard servlet response instance.
     * @param errors Map of error messages.
     * @param errorMsg error message.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondFail(HttpServletResponse response, Map<String, String> errors, String errorMsg)
            throws IOException;

    /**
     * Responds a custom serializable object.
     *
     * @param response HttpServletResponse
     * @param respObj custom response object.
     * @throws IOException Required for serialization of the object into the view.
     */
    void respondCustom(HttpServletResponse response, Map<String, Object> respObj) throws IOException;
}
